What is heroku-client?
The heroku-client npm package is a JavaScript client library for the Heroku Platform API. It allows developers to interact with Heroku's services programmatically, enabling automation and integration with other tools and services.
What are heroku-client's main functionalities?
Authentication
This feature allows you to authenticate with the Heroku API using an API token. This is the first step to interact with Heroku services programmatically.
const Heroku = require('heroku-client');
const heroku = new Heroku({ token: 'YOUR_HEROKU_API_TOKEN' });
List Apps
This feature allows you to list all the applications associated with your Heroku account. The code sample demonstrates how to fetch and log the list of apps.
heroku.get('/apps').then(apps => console.log(apps));
Create App
This feature allows you to create a new Heroku application. The code sample shows how to create an app named 'my-new-app'.
heroku.post('/apps', { body: { name: 'my-new-app' } }).then(app => console.log(app));
Delete App
This feature allows you to delete an existing Heroku application. The code sample demonstrates how to delete an app named 'my-new-app'.
heroku.delete('/apps/my-new-app').then(response => console.log(response));
Get Config Vars
This feature allows you to retrieve the configuration variables for a specific Heroku application. The code sample shows how to fetch and log the config vars for 'my-new-app'.
heroku.get('/apps/my-new-app/config-vars').then(configVars => console.log(configVars));
Other packages similar to heroku-client
heroku-cli-util
The heroku-cli-util package provides utilities for building Heroku CLI plugins. While it is not a direct replacement for heroku-client, it offers functionalities that can be useful for extending the Heroku CLI with custom commands and integrations.
heroku-api
The heroku-api package is a Ruby client for the Heroku API. It provides similar functionalities to heroku-client but is intended for use in Ruby applications. It allows developers to manage Heroku apps, config vars, and other resources programmatically.
heroku-client
![Code Climate](https://codeclimate.com/github/heroku/node-heroku-client/badges/gpa.svg)
A wrapper around the v3 Heroku API.
Install
$ npm install heroku-client --save
Usage
To begin, require the Heroku module and create a client, passing in an API
token:
const Heroku = require('heroku-client')
const heroku = new Heroku({ token: process.env.HEROKU_API_TOKEN })
heroku-client has get
, post
, patch
, and delete
functions which can make
requests with the specified HTTP method to any endpoint:
heroku.get('/apps').then(apps => {
})
heroku.post('/apps').then(app => {})
heroku.post('/apps', {body: {name: 'my-new-app'}}).then(app => {})
heroku.patch('/apps/my-app', {body: {name: 'my-renamed-app'}}).then(app => {})
heroku.delete('/apps/my-old-app').then(app => {})
There is also an even more generic request
function that can accept many more
options:
heroku.request({
method: 'GET',
path: '/apps',
headers: {
'Foo': 'Bar'
},
parseJSON: false
}).then(response => {})
Generators
It's easy to get heroku-client working with generators. In this
example, I'll use the co library to wrap a function that will get the list
of all of my apps, and then get the dynos for each of those apps:
const co = require('co')
const heroku = require('heroku-client')
const hk = heroku.createClient({ token: process.env.HEROKU_API_KEY })
let main = function * () {
let apps = yield hk.get('/apps')
let dynos = yield apps.map(getDynos)
console.log(dynos)
function getDynos(app) {
return hk.get(`/apps/${app.name}/dynos`)
}
}
co(main)()
Hooray, no callbacks or promises in sight!
HTTP Proxies
If you'd like to make requests through an HTTP proxy, set the
HEROKU_HTTP_PROXY_HOST
environment variable with your proxy host, and
HEROKU_HTTP_PROXY_PORT
with the desired port (defaults to 8080). heroku-client
will then make requests through this proxy instead of directly to
api.heroku.com.
Caching
heroku-client can optionally perform caching of API requests.
heroku-client will cache any response from the Heroku API that comes with an
ETag
header, and each response is cached individually (i.e. even though the
client might make multiple calls for a user's apps and then aggregate them into
a single JSON array, each required API call is individually cached). For each
API request it performs, heroku-client sends an If-None-Match
header if there
is a cached response for the API request. If API returns a 304 response code,
heroku-client returns the cached response. Otherwise, it writes the new API
response to the cache and returns that.
To tell heroku-client to perform caching, add a config object to the options
with store and encryptor objects. These can be instances of memjs and
simple-encryptor, respectively.
var Heroku = require('heroku-client');
var memjs = require('memjs').Client.create();
var encryptor = require('simple-encryptor')(SECRET_CACHE_KEY);
var hk = new Heroku({
cache: { store: memjs, encryptor: encryptor }
});
Custom caching
Alternatively you can specify a custom cache implementation. Your custom implementation must define get(key, cb(err, value))
and set(key, value)
functions.
Here's a sample implementation that uses Redis to cache API responses for 5-minutes each:
var redis = require('redis');
var client = redis.createClient();
var cacheTtlSecs = 5 * 60;
var redisStore = {
get: function(key, cb) {
var redisKey = 'heroku:api:' + key;
client.GET(redisKey, cb);
},
set: function(key, value) {
var redisKey = 'heroku:api:' + key;
client.SETEX(redisKey, cacheTtlSecs, value, function(err) {
});
}
};
var encryptor = require('simple-encryptor')(SECRET_CACHE_KEY);
var Heroku = require('heroku-client');
var hk = new Heroku({
cache: {store: redisStore, encryptor: encryptor}
});
Contributing
Inspect your changes, and
bump the version number accordingly when cutting a
release.
Running tests
heroku-client uses ava for tests:
$ npm test